home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d20 / doorskl3.arc / DOORSKEL.DOC < prev    next >
Text File  |  1992-01-15  |  12KB  |  254 lines

  1. DOORSKEL.LZH Documentation
  2. ==========================
  3.  
  4.  
  5. DOORSKEL is a skeleton for writing your own PC Doors in C.  The source
  6. supports both Turbo C 2.0 and MSC 6.0a.  The Doors you write can read
  7. either DORINFO?.DEF or XBBS' BBS-specific files.  THEY WILL WORK WITH
  8. ANY BBS THAT USES A DORINFO?.DEF FILE AND/OR CAN PASS COMMAND LINE
  9. ARGUMENTS; YOU ARE NOT LIMITED TO USING THESE DOORS WITH XBBS.  THEY
  10. REQUIRE A FOSSIL DRIVER.
  11.  
  12. I'm not going to hold your hand in these docs.  If you don't know how to
  13. program in C, either learn how first or be prepared to do your homework
  14. as you go along.  DOORSKEL is simple to use, but it is in C, not
  15. GWBASIC; a simple book in Greek might be hard for you to read if you
  16. can't read Greek...
  17.  
  18. The first four .C files (DOORSKEL.C, DOORSKL2.C, DOORMISC.C and MTASK.C)
  19. contain support and startup functions.  DOORSKL3.C contains a file
  20. reading function.  DOORSKL4.C contains an empty function (mainloop())
  21. which is where you start writing your own code. The main() function (in
  22. DOORSKEL.C) calls mainloop() after it starts up the Door. By the time
  23. mainloop() executes, the FOSSIL is hot, screen cleared and status line
  24. displayed, command line arguments parsed, info files read and global
  25. variables set up.  You can go to town.  When your program returns from
  26. mainloop(), the FOSSIL is flushed and deinitialized. DOORSKL5.C contains
  27. CRC-16 and CRC-32 code which you can use to implement file transfer
  28. protocols or whatever.  DOORANSI.C contains some fancy ANSI input
  29. routines, and DOORHELP.C contains user help functions.
  30.  
  31. Please take the time to look at the support functions and read the
  32. comments in all files (including particularly DOORSKEL.H) so you don't
  33. reinvent the wheel and see how to take advantage of what you've been
  34. provided.  Most of the commonly asked questions (how do I do xxx when
  35. writing a Door in C?) have been addressed, including disabling
  36. control-break, checking carrier and time, displaying files, inputting
  37. keys and strings, and writing to both the screen (through ANSI.SYS or
  38. equivalent driver) and modem while maintaining a local status line.
  39. Trust me, it's worth the time.  If you can't write a fancy Door with
  40. what's in this thing, you may as well hang up your programming hat.
  41.  
  42. The SCREEN2.ASM/OBJ files in the archive were lifted from jim nutt's
  43. MSGED 2.0 source code (it's marked "public domain" within an inch of its
  44. life).  Thanks to jim (I assume he wrote it).  Turbo C's cprintf()
  45. contains a big bug (won't write to lines below 25 in 43/50/60 line
  46. mode), so this made it much easier.  The OBJ is compiled in large model,
  47. but you'll note the prototypes in doorskel.h that allow you to use it
  48. (carefully, maybe) in small models.  There's also ANSI.ASM/OBJ files in
  49. the archive that came from the RBBS source and were heavily modified.
  50.  
  51. Although you can consider most of this code a "black box," you might
  52. want to wedge some command line arguments into main() or add something
  53. to the deinit() code executed when the program exit()s.  I've tried to
  54. leave you comments about what each function does.  Hopefully the
  55. #defines to get the code to work with either Turbo C or MSC won't get
  56. too much in the way of your understanding.  I provided complete source
  57. instead of some sort of library so that anything you don't like can be
  58. adjusted.  But, please, for your own sake, make changes slowly, if at
  59. all, to the existing code, and only after trying it out as is first!
  60. You'll save yourself some headaches...
  61.  
  62. If you need to ask a question, send me netmail.  Poll again in a few
  63. days for a reply.
  64.  
  65. Keep in mind what you paid for DOORSKEL before you write me just to
  66. bitch.  On the other hand, constructive criticism, suggestions and
  67. wish-lists are welcome.
  68.  
  69.  
  70. The Doorskel archive contains SAMPLE.C, which can be used to create the
  71. sample Door SAMPLE.EXE (also included, compiled with TC 2.0).  SAMPLE.C
  72. is DOORSKL4.C with mainloop() (the function where your coding starts)
  73. filled in.  This is provided as a simple example of how to use the kit
  74. to create a running .EXE, and so you can quickly satisfy yourself that
  75. the code works.  SAMPLE H for help on how to use it.
  76.  
  77.  
  78. I've also added XBBSMSG.LZH to the archive.  This can let you write code
  79. that interfaces directly and safely with the XBBS message bases if you've
  80. got the urge.
  81.  
  82.  
  83. Most commonly used functions:   (see prototypes in doorskel.h)
  84. ============================
  85.  
  86. hitreturn:      display "Press [Enter] to continue: " and wait for
  87.                 [Enter] to be pressed
  88. cls:            clear local and remote screens
  89. debug_print:    display messages locally only, and then only if debug
  90.                 mode is turned on at the command line with "!".  Handy
  91.                 for testing.
  92. addtolog:       write a string to a logfile (default is XBBS.LOG set in
  93.                 DOORSKEL.C)
  94. inkey:          mimics BASIC's INKEY$ function; basic method of getting
  95.                 a character from the user.  returns 0 if no char
  96.                 available.  handles special keys (like ALT-+ for more
  97.                 time, ALT-H to hang up, etc. from local, ANSI cursor and
  98.                 Doorway keys from remote)
  99. genin:          generic input routine.  very versatile.
  100. printfm:        printf-clone for both local and remote.
  101. spawnit:        spawn a program.  Handles clearing screen before spawn
  102.                 and clearing screen and restoring status line after.
  103. mainloop:       where your coding really starts, in DOORSKL4.C
  104. printm:         print a string to local and remote; no formatting like
  105.                 printfm.
  106. printg:         like printm but only sends string if user has ANSI
  107.                 graphics on.
  108. mprint:         print a string to remote only, no formatting.
  109. deinitialize:   exit routine established in DOORSKEL.C via atexit().
  110.                 disables FOSSIL, closes all files, etc.  You can add
  111.                 things to this (it's in DOORSKEL.C).
  112. ansi:           print a string locally only; protects status line.  No
  113.                 formatting.  this function is in ANSI.ASM (compiled in
  114.                 large mode in provided ANSI.OBJ; see prototypes in
  115.                 doorskel.h).
  116. readtext:       super-duper file reader for remote users.  try it,
  117.                 you'll like it.  It's in DOORSKL3.C and does everything
  118.                 but make coffee in the morning.
  119. dputc:          direct screen putc
  120. dputs:          direct screen puts (no cr/lf terminator added)
  121. dprintf:        direct screen printf
  122. fossil:         handles most common FOSSIL int 14H calls.  see also
  123.                 macros defined in doorskel.h for convenience.
  124.  
  125. Global variables of interest:  (already set when mainloop() executes)
  126. ============================
  127.  
  128. maxx, maxy:     width and length of the local screen.
  129. current_color:  used by direct screen writing functions as color for
  130.                 text.
  131. debug_mode:     if non-zero, debug_print will display text locally.
  132. graphics:       non-zero if user has ANSI graphics capability on.
  133. timelimit:      user's time tracking variable.  use macro MinsLeft
  134.                 (defined in doorskel.h) to get something easier to work
  135.                 with, or check getxbbstime() to see how it's used.
  136. baud:           0 if local, otherwise baud rate of user
  137. numlines:       length of user's screen
  138. width:          width of user's screen
  139. seclvl:         security level of user
  140. commport:       port program is communicating with if baud > 0; 0-based
  141.                 so that 0 = COM1 (the way FOSSILs like it)
  142. logfile:        name of logfile to which addtolog will write.
  143. username:       name of user.
  144. nodenumber:     node of caller (for multiline systems).
  145.  
  146. (#defining XBBS causes some other interesting variables to be created)
  147.  
  148.  
  149. (Note:  I'll add to this list and the descriptions as I get time)
  150.  
  151.  
  152.  
  153. Special local keys supported by DOORSKEL:
  154.  
  155. ALT-H:  hang up, end program
  156. ALT-J:  jump to local DOS shell
  157. ALT-+:  increase time by 1 minute
  158. ALT--:  decrease time by 1 minute
  159. ALT-C:  enter/exit chat mode
  160. CTRL-C: if DISABLEBREAK isn't defined, works as expected
  161. CTRL-ALT-DEL: guess
  162.  
  163.  
  164. Doorskel reads ANSI escape sequences from the remote for cursor
  165. movement, and processes "Doorway" keys.  Take a look at specialmod() in
  166. doorskel.c to see how it works.
  167.  
  168.  
  169. This code does produce warnings; it's not completely "clean".  As far as
  170. I can tell, it works fine.  It's been cobbled together from doors and
  171. BBSes I've written, as an explanation for its slovenliness.  And
  172. remember, I'm a self-taught ex-BASIC programmer who just does this as a
  173. hobby.  If someone wants to clean up all the warnings and send me the
  174. code, more power to them; I'd appreciate it.  Just don't let the
  175. warnings scare you too much.
  176.  
  177.  
  178.  
  179. Log of changes:
  180. ==============
  181.  
  182. /* 10/24/91 */
  183.  
  184. Moved some functions from DOORSKEL.C to DOORMISC.C; not sure why, but I
  185. did.  Include DOORMISC.C in any project where you include DOORSKEL.C
  186. (read: all projects).
  187.  
  188. Added MTASK.C (routines in DOORSKEL.C call what's needed, so don't worry
  189. about it, just include it in your project) to allow DOORSKEL doors to
  190. get along with multitaskers (give up time slices).  SAMPLE.EXE in the
  191. archive is still the one compiled with the old package (just too lazy to
  192. recompile).  If you're curious but lazy (aren't we all?), reference to
  193. set_mtask() is in main() and references to pause_mtask() are in inkey()
  194. and my_sleep().
  195.  
  196. /* 10/27/91 */
  197.  
  198. Added DOORHELP.C and DOORANSI.C containing functions lifted from XDB's
  199. source code.  I haven't attempted to compile these as part of a Doorskel
  200. project, so you might have to tweak here and there.  They provide help
  201. facilities and fancy-ANSI menus.
  202.  
  203. /* 12/01/91 */
  204.  
  205. Did some work, testing, clarification, etc. to make Doorskel smaller and
  206. somewhat easier to read and use.  Pay particular attention to the
  207. comments in DOORSKEL.H (now arranged in blocks so you can find the part
  208. you're interested in more easily) and at the top of each module.
  209. Recompiled SAMPLE.EXE with MSC this time (in small model, just to make
  210. sure it could be done, with no optimizations). Included MSC 6.0
  211. SAMPLE.MAK and TC 2.01 SAMPLE.PRJ files so you can reconstruct
  212. SAMPLE.EXE for testing.  If you have a compiler other than TC 2.01 or
  213. MSC 6.0x, hopefully the portability stuff I've already put in will make
  214. it fairly easy to modify the code to work with your compiler.  By all
  215. means, send me what it took to get it to work to incorporate into future
  216. releases.
  217.  
  218. /* 12/05/91 */
  219.  
  220. Found and fixed a bug; ANSI.ASM didn't have SETFASTANSI declared PUBLIC.
  221. Compiled under small and compact models of TC 2.01 to test compatibility
  222. code.  Replaced MSC small model SAMPLE.EXE with TC's for the hell of it.
  223.  
  224. /* 12/16/91 */
  225.  
  226. Added another fancy input module (SELECT1.C) and modified the sample
  227. Door to use its selection routines.  Replaced TC small model .EXE with
  228. an MSC large model, again, for the hell of it.  Tweaked here and there.
  229. Put the stuff that needs to be redefined for each new Door (name of
  230. Door, interface type, etc.) into a separate THISPROJ.H file that
  231. DOORSKEL.H includes so that you don't have to much around with
  232. DOORSKEL.H when starting a new project.
  233.  
  234.  
  235.  
  236.  
  237. Except where specifically noted in the source,
  238.  
  239.   DOORSKEL is copyright (c) 1990/91 by M. Kimes, All Rights Reserved.
  240.  
  241. It may be freely used for >>>FREE<<< programs as long as you don't try
  242. to save any souls (nasty habit).  Any freely given, unsolicited
  243. donations will go to the "buy the wife some pizza" fund.
  244.  
  245. If you want to make money on a program you write with it, give me a call
  246. and we'll work something reasonable out.  If you want to save souls with
  247. a program you write with it, go directly to hell.
  248.  
  249.  
  250.  
  251. M. Kimes
  252. 1:380/16.0@Fidonet
  253. (318)222-3455 data
  254.